/*
 * Copyright 2002-2016 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.web.servlet.mvc.condition;

import javax.servlet.http.HttpServletRequest;

/**对于@RequestMapping注解中的不同属性，使用不同类型的请求条件进行封装
 * <br/>Contract for request mapping conditions.
 *
 * <p>Request conditions can be combined via {@link #combine(Object)}, matched to
 * a request via {@link #getMatchingCondition(HttpServletRequest)}, and compared
 * to each other via {@link #compareTo(Object, HttpServletRequest)} to determine
 * which is a closer match for a given request.
 *
 * @author Rossen Stoyanchev
 * @author Arjen Poutsma
 * @since 3.1
 * @param <T> the type of objects that this RequestCondition can be combined
 * with and compared to
 */
public interface RequestCondition<T> {

	/**合并两个条件。用于把当前请求条件实例与参数中请求条件实例进行合并，在映射信息合并时有用
	 * <br/>Combine this condition with another such as conditions from a type-level and method-level {@code @RequestMapping} annotation.
	 * @param other the condition to combine with.
	 * @return a request condition instance that is the result of combining
	 * the two condition instances.
	 */
	T combine(T other);

	/**获取与请求匹配条件实例，即与当前条件的匹配结果。用于获取请求条件实例中与当前请求匹配的条件信息，一般是请求条件实例的一个子集。
	 * <br/>如RequestMethodRequestCondition请求方法条件，传入的请求方法列表是HttpMethod.GET与HttpMethod.POST，当传入请求的请求方法为GET时，该方法返回的匹配结果为只包含HttpMethod.GET的RequestMethodRequestCondition实例，即只返回与请求匹配的部分条件内容
	 * <br/>Check if the condition matches the request returning a potentially new
	 * instance created for the current request. For example a condition with
	 * multiple URL patterns may return a new instance only with those patterns
	 * that match the request.
	 * <p>For CORS pre-flight requests, conditions should match to the would-be,
	 * actual request (e.g. URL pattern, query parameters, and the HTTP method
	 * from the "Access-Control-Request-Method" header). If a condition cannot
	 * be matched to a pre-flight request it should return an instance with
	 * empty content thus not causing a failure to match.
	 * @return a condition instance in case of a match or {@code null} otherwise.
	 */
	T getMatchingCondition(HttpServletRequest request);

	/**匹配结果比较。在获取请求匹配条件时，返回的也是请求条件实例，该方法用于对getMatchingCondition返回的请求匹配结果进行比较，在存在多个与请求匹配的映射信息时对映射信息进行排序
	 * <br/>Compare this condition to another condition in the context of
	 * a specific request. This method assumes both instances have
	 * been obtained via {@link #getMatchingCondition(HttpServletRequest)}
	 * to ensure they have content relevant to current request only.
	 */
	int compareTo(T other, HttpServletRequest request);

}
